home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / pcl4p51.zip / PCL4PUSR.DOC < prev    next >
Text File  |  1996-06-05  |  87KB  |  2,178 lines

  1.  
  2.  
  3.                                Personal Communications Library
  4.  
  5.                                   For Borland/Turbo Pascal
  6.  
  7.  
  8.                                          (PCL4P)
  9.  
  10.  
  11.  
  12.                                       USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                        Version  5.1
  19.  
  20.                                        June 5, 1996
  21.  
  22.  
  23.  
  24.  
  25.                              This software is provided as-is.
  26.                       There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                                    Copyright (C) 1996
  32.                                    All rights reserved
  33.  
  34.  
  35.  
  36.                                 MarshallSoft Computing, Inc.
  37.                                    Post Office Box 4543
  38.                                    Huntsville AL 35815
  39.  
  40.                                  Voice : 205-881-4630
  41.                                    FAX : 205|880|0925
  42.                                    BBS : 205-880-9748
  43.                                  email : help@marshallsoft.com
  44.                               Anon FTP : ftp.marshallsoft.com
  45.                                    web : www.marshallsoft.com
  46.  
  47.  
  48.  
  49.  
  50.                                             _______
  51.                                        ____|__     |                (R)
  52.                                     --+       |    +-------------------
  53.                                       |   ____|__  |  Association of
  54.                                       |  |       |_|  Shareware
  55.                                       |__|   o   |    Professionals
  56.                                     --+--+   |   +---------------------
  57.                                          |___|___|    MEMBER
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.              PCL4P Users Manual                                                Page 1
  69.                                    C O N T E N T S
  70.  
  71.  
  72.  
  73.  
  74.  
  75.                 Chapter                                                   Page
  76.  
  77.                 1.0 Introduction................................................3
  78.                     1.1 User Support............................................4
  79.                     1.2 ASP Ombudsman...........................................4
  80.                     1.3 A Typical Application...................................5
  81.                     1.4 Installation............................................6
  82.                 2.0 Library Organization........................................7
  83.                     2.1 Configuration...........................................7
  84.                     2.2 Initialization & Termination............................7
  85.                     2.3 Modem Control & Status..................................8
  86.                     2.4 Serial I/O..............................................8
  87.                     2.5 Error Detection.........................................9
  88.                     2.6 General Support.........................................9
  89.                 3.0 Library Overview...........................................10
  90.                     3.1 Using the Library......................................10
  91.                     3.2 Protected Mode.........................................10
  92.                     3.3 Application Notes .....................................11
  93.                         3.3.1 Terminal Programs................................11
  94.                         3.3.1 Door Programs....................................11
  95.                         3.3.2 BBS Programs.....................................11
  96.                     3.4 Compiling & Linking....................................12
  97.                     3.5 Turbo Vision...........................................12
  98.                 4.0 Talking to Your Modem......................................13
  99.                     4.1 Modem Standards........................................13
  100.                     4.2 Flow Control...........................................14
  101.                     4.3 MODEM_IO functions.....................................14
  102.                     4.4 Modem Initialization...................................15
  103.                 5.0 Problems...................................................16
  104.                 6.0 Serial Communications......................................17
  105.                     6.1 Communications Basics..................................17
  106.                     6.2 Standard Port Addresses................................18
  107.                     6.3 Running 3 or 4 Ports Concurrently......................19
  108.                     6.4 Using Multiport Cards..................................20
  109.                         6.4.1 The DigiBoard....................................20
  110.                         6.4.2 The BOCA Board...................................20
  111.                     6.5 Transmitter Interrupts.................................21
  112.                     6.6 RS232 Signals..........................................22
  113.                     6.7 National INS8250, INS16450, and INS16550 UARTs.........23
  114.                     6.8 Register Summary.......................................24
  115.                 7.0 Example Programs...........................................26
  116.                     7.1 MINIMAL................................................26
  117.                     7.2 SIMPLE.................................................26
  118.                     7.3 LOGIN..................................................26
  119.                     7.4 DOOR...................................................26
  120.                     7.5 SELFTEST...............................................26
  121.                 8.0 Legal Issues...............................................27
  122.                     8.1 Registration...........................................27
  123.                     8.2 License................................................27
  124.                     8.3 Warranty...............................................28
  125.                 9.0 Summary....................................................29
  126.                     9.1 Revision History.......................................29
  127.                     9.2 Function Summary.......................................31
  128.                     9.3 Further Reading........................................31
  129.                10.0 Other MarshallSoft Computing products for Pascal...........32
  130.                     10.1 The Personal Protocol Library for Pascal..............32
  131.                     10.2 The Personal Communication Library for DELPHI.........32
  132.                11.0 Other MarshallSoft Computing shareware products............32
  133.  
  134.  
  135.  
  136.              PCL4P Users Manual                                                Page 2
  137.               1.0 Introduction
  138.  
  139.  
  140.               The  Personal  Communications Library for Borland/Turbo Pascal (PCL4P) is an
  141.               asynchronous  communications  library  designed  for  experienced   software
  142.               developers programming in Turbo or Borland Pascal. The PCL features:
  143.  
  144.               o 36 communications and support functions.
  145.               o Supports 16-bit protected mode [requires Borland Pascal].
  146.               o Support for the high performance 16550 UART.
  147.               o Supports hardware (RTS/CTS) flow control.
  148.               o Interrupt driven receiver and transmitter.
  149.               o Supports 300 baud to 115,200 baud.
  150.               o Supports the DigiBoard PC/4 and PC/8.
  151.               o Supports the BOCA BB1004, BB1008, and BB2016 boards.
  152.               o Supports COM1 through COM8 (through COM20 with multiport board)
  153.               o Adjustable receive queues from 8 bytes to 32 KB.
  154.               o Control-BREAK error exit.
  155.               o Use IRQ2 through IRQ15 with any UART address.
  156.               o 18 communications error conditions trapped.
  157.               o Allows 4 ports to run concurrently (20 with multiport board).
  158.               o Complete modem control & status.
  159.               o Written in assembly language for small size & high speed.
  160.               o Terminal program featuring ASCII (with XON/XOFF), XMODEM, YMODEM,
  161.                 and YMODEM-G. [Source in protocol library PPL4P].
  162.  
  163.  
  164.               Why should you buy PCL4P ?  Several good reasons are:
  165.  
  166.                 COMPLETE - PCL4P is complete since it provides absolute control
  167.                            of the serial ports (including the high  performance
  168.                            INS16550).
  169.  
  170.                  COMPACT - PCL4P  is  very compact  at  less  than  8  KB. Your
  171.                            application doesn't carry a lot of excess code.
  172.  
  173.                     FAST - PCL4P is fast since it will  run  at  38400  baud  on
  174.                            even  slow  8088 PCs (4.77 MHZ) and at 115200 baud on
  175.                            most everything else.
  176.  
  177.                  SUPPORT - If you get stuck,  you talk  to  the programmer  that
  178.                            wrote the code, not a  person  hired  to  answer  the
  179.                            phone.
  180.  
  181.                      BBS - A BBS is available (2400 to 14400 baud, N81) in order
  182.                            to provide immediate support as necessary. You can also
  183.                            email us at help@marshallsoft.com.
  184.  
  185.               NEWSLETTER - MSC  newsletter discusses communications problems and
  186.                            solutions (published quarterly).
  187.  
  188.                    PRICE - You get PCL4P for a very reasonable price ($75) !
  189.  
  190.                 UPGRADES - Once you buy PCL4P, you can always update to  the  most
  191.                            recent version very inexpensively ($25 plus shipping).
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.              PCL4P Users Manual                                                Page 3
  205.               1.1 User Support
  206.  
  207.  
  208.               We want you to be successful in developing your applications using PCL4P! We
  209.               depend  on  our  customers to let us know what they need in a communications
  210.               library.  This means we are committed to providing the  best  communications
  211.               library  that we can. If you have any suggestions or comments, please let us
  212.               know!
  213.  
  214.               We provide customer support for registered users by voice, FAX, BBS,  email,
  215.               and  mail.   We  provide  limited  support  for unregistered users by voice,
  216.               email, and BBS only.
  217.  
  218.               If  you  are  having  a problem using PCL4P, call us at 205-881-4630 between
  219.               1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at  other
  220.               times and leave a message, and call back later for a reply. Registered users
  221.               (ONLY) can also FAX us at 205-880-0925 at any time (24 hours). You can  also
  222.               email us at help@marshallsoft.com.
  223.  
  224.               However,  we  can  only  answer  questions  with  respect to using the PCL4P
  225.               library.  We cannot help you program your application, but we'll be glad  to
  226.               discuss it with you.
  227.  
  228.               You  may  also  call  our User Support BBS (2400 to 14400 baud, no parity, 8
  229.               data bits, 1 stop bit) at 205-880-9748 and leave a message  (address  it  to
  230.               the SYSOP).  We will usually have a reply ready for you within 24 hours.
  231.  
  232.               The BBS is available 24 hours per day. All files are in standard ZIP format.
  233.               The  BBS  will  contain  the  latest  shareware  version of all MarshallSoft
  234.               Computing products as well as related files such as:
  235.  
  236.                   BUGS.ZIP     -  Bug report.
  237.                   NEWS.ZIP     |  Latest news regarding our products.
  238.                   PRODUCTS.ZIP -  List of all shareware products.
  239.  
  240.               The MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is  published
  241.               quarterly.  It discusses various communications problems and solutions using
  242.               PCL4P  as  well  as related information. "Comm Talk" is published on our Web
  243.               site www.marshallsoft.com and is available in text form on our BBS  and  FTP
  244.               site (ftp.marshallsoft.com/marshallsoft).
  245.  
  246.  
  247.  
  248.               1.2 ASP Ombudsman
  249.  
  250.  
  251.               MarshallSoft Computing, Inc.  is a member of the  Association  of  Shareware
  252.               Professionals  (ASP).   ASP  wants to make sure that the shareware principle
  253.               works for you.  If you are unable to  resolve  a  shareware-related  problem
  254.               with  an  ASP  member  by contacting the member directly, ASP may be able to
  255.               help. The ASP Ombudsman can help you resolve a dispute or  problem  with  an
  256.               ASP  member,  but  does not provide technical support for members' products.
  257.               Please write to the ASP Ombudsman at  545  Grover  Road,  Muskegon,  MI  USA
  258.               49442-9427,  Fax  616-788-2765,  or send a CompuServe message via CompuServe
  259.               Mail to ASP Ombudsman 70007,3536.
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.              PCL4P Users Manual                                                Page 4
  273.               1.3 A Typical Application
  274.  
  275.  
  276.               In general, there are two classes of applications that use a  communications
  277.               library  like PCL4P - those that use a modem to connect to the outside world
  278.               and those that connect directly to a peripheral device. In  either  case,  a
  279.               typical  application  program using PCL4P might look like the following code
  280.               outline:
  281.  
  282.  
  283.  
  284.               +----------------------------------------------------------------+
  285.               |                                                                |
  286.               | program YourProgram                                            |
  287.               |                                                                |
  288.               | uses PCL4P;                                                    |
  289.               | ...                                                            |
  290.               | var BufPtr : Pointer;                                          |
  291.               |     BufSeg : Integer;                                          |
  292.               |                                                                |
  293.               | ...                                                            |
  294.               | begin (* YourProgram *)                                        |
  295.               |    (* allocate RX buffer memory *)                             |
  296.               |    GetMem(BufPtr,1024+16);                                     |
  297.               |    BufSeg := (Seg(BufPtr^)+1) + (Ofs(BufPtr^) SHR 4);          |
  298.               |    RetCode := SioRxBuf(Port,BufSeg,Size1024);                  |
  299.               |    (* allocate TX buffer memory *)                             |
  300.               |    GetMem(BufPtr,128+16);                                      |
  301.               |    BufSeg := (Seg(BufPtr^)+1) + (Ofs(BufPtr^) SHR 4);          |
  302.               |    RetCode := SioTxBuf(Port,BufSeg,Size128);                   |
  303.               |    (* initialize port *)                                       |
  304.               |    RetCode := SioParms(Port,NoParity,OneStopBit,WordLength8);  |
  305.               |    RetCode := SioReset(Port,Baud2400);                         |
  306.               |    ...                                                         |
  307.               |    ... ( application code )                                    |
  308.               |    ...                                                         |
  309.               |    RetCode := SioDone(Port);                                   |
  310.               | end. (* YourProgram *)                                         |
  311.               +----------------------------------------------------------------+
  312.  
  313.  
  314.  
  315.               In  the  above example, SioRxBuf is called to set up the a 1024 byte receive
  316.               buffer. SioTxBuf is called to  set  up  the  128  byte  transmitter  buffer.
  317.               SioParms  is  called  to set up the parity, stop bit count, and word length.
  318.               SioReset is called to  set  the  baud  rate  to  2400  and  reset  the  UART
  319.               (Universal Asynchronous Receiver / Transmitter).
  320.  
  321.               Before leaving your application, SioDone is  called  to  restore  the  prior
  322.               state of the serial communications system.
  323.  
  324.               If  you  are using a modem, you also need to be concerned about initializing
  325.               your  modem  correctly  and  handling  any required flow control.  Refer  to
  326.               Chapter 4.0, "Talking to Your Modem" for detailed information.
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.              PCL4P Users Manual                                                Page 5
  341.               1.3 Installation
  342.  
  343.  
  344.               (1) Before installation of PCL4P, your compiler should already be  installed
  345.               on  your system and tested. If you are not familiar with makefiles, refer to
  346.               your compiler manual.  Examine the file "FILES.LST" for a list  of  all  the
  347.               distribution files.
  348.  
  349.               (2)  Make  a  backup  copy  of  your  distribution  disk.  Put your original
  350.               distribution disk in a safe place.
  351.  
  352.               (3) Create a work directory on your work disk (normally your harddisk).  For
  353.               example,  to create a work directory named PCL4P, we first log onto the work
  354.               disk and then type:
  355.  
  356.                      MKDIR PCL4P
  357.  
  358.               (4) Copy all the files from your backup copy of  the  distribution  disk  to
  359.               your  work  directory.   For example, to copy from the A: drive to your work
  360.               directory, we type:
  361.  
  362.                      CD PCL4P
  363.                      COPY A:*.*
  364.  
  365.  
  366.               (5) The library unit must be created by running:
  367.  
  368.                      TP_REAL.BAT : Creates PCL4P.TPU [real mode] using Turbo Pascal.
  369.                      BP_REAL.BAT : Creates PCL4P.TPU [real mode] using Borland Pascal.
  370.                      BP_PROT.BAT : Creates PCL4P.TPP [prot mode] using Borland Pascal.
  371.  
  372.  
  373.               (6) Compile SIMPLE.PAS:
  374.  
  375.                      TPC SIMPLE  - if using Turno Pascal.
  376.                      BPC SIMPLE  - if using Borland Pascal.
  377.  
  378.               SIMPLE.PAS should compile without any problems.
  379.  
  380.               (7)  The  recommended  way  to  test  SIMPLE  is  to run it on two computers
  381.               connected by a null modem cable.  Whatever is typed on one  computer  should
  382.               be displayed on the other. SIMPLE can also be tested by connecting your port
  383.               to a modem.
  384.  
  385.               (8)  Compile  and  run the remaining example programs. In partcular, compile
  386.               the protected mode program SIMPLE16.PAS if using Borland Pascal.
  387.  
  388.                     BPC /CP SIMPLE16.PAS
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.              PCL4P Users Manual                                                Page 6
  409.               2.0 Library Organization
  410.  
  411.  
  412.               The  PCL4P  library  is organized into six categories of functions. Refer to
  413.               the PCL Reference Manual (PCL4P.REF) for details on individual functions.
  414.  
  415.  
  416.               2.1 Configuration
  417.  
  418.  
  419.               There are three functions in the configuration category.  SioPorts  is  used
  420.               to  set  the number of PC ports, specify the first DigiBoard (or BOCA board)
  421.               port, and set the DigiBoard (or BOCA board) status register address. SioUART
  422.               is used to change the UART base address  for  a  communications  port  to  a
  423.               non-standard  address, while SioIRQ is used to assign a nonstandard IRQ line
  424.               to a port.  (See Chapter 6.0, Serial  Communications  for  more  details  on
  425.               standard UART addresses and IRQ lines).
  426.  
  427.               The  configuration  functions  SioPorts,  SioUART  and SioIRQ must be called
  428.               before calling any other library functions.  Be very careful in using  these
  429.               functions.  Remember that your serial hardware must support the UART and IRQ
  430.               that you specify.
  431.  
  432.               SioPorts - Set # PC ports, 1st DigiBoard (or BOCA board) port.
  433.               SioUART  | Sets the UART base address.
  434.               SioIRQ   - Assigns an IRQ line to a port.
  435.  
  436.               THE IRQ GOLDEN  RULE:  You  may  open (via SioReset) only one port per IRQ
  437.               (except for the DigiBoard and BOCA board).
  438.  
  439.  
  440.               2.2 Initialization & Termination
  441.  
  442.  
  443.               There are eight functions in the initialization  and  termination  category.
  444.               Together,  SioParms,  SioFIFO,  SioRxBuf,  SioTxBuf, and SioReset initialize
  445.               your serial communications system.  Your application must call SioParms  and
  446.               SioRxBuf  before  calling  SioReset,  and SioReset must be called before any
  447.               serial I/O processing can be done.
  448.  
  449.               After initialization, SioParms and SioBaud can be called again to change the
  450.               communications parameters without resetting the serial port. SioFlow can  be
  451.               called to enable hardware flow control.
  452.  
  453.               Before  exiting  from  your  application, SioDone must be called. Failure to
  454.               call SioDone can crash your system later.
  455.  
  456.               SioRxBuf   - Sets up receive buffer.
  457.               SioTxBuf   | Sets up transmitter buffer.
  458.               SioFIFO    | Sets the interrupt level for the INS16550.
  459.               SioParms   | Sets parity, stop bits, and word length.
  460.               SioReset   | Initialize a serial port for processing.
  461.               SioDone    | Terminates further serial processing.
  462.               SioBaud    | Sets the baud rate of the selected port.
  463.               SioFlow    - Enables / disables flow control.
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.              PCL4P Users Manual                                                Page 7
  477.               2.3 Modem Control & Status
  478.  
  479.  
  480.               There are nine functions in the modem  control  and  status  category  which
  481.               provide  your  application with complete control over the status and control
  482.               bits of your modem.
  483.  
  484.               There are two modem control bits, "Data Terminal Ready" (DTR)  and  "Request
  485.               To  Send"  (RTS).  These  bits  can  be  read, set, or cleared by SioDTR and
  486.               SioRTS.
  487.  
  488.               There are four modem status bits, "Data Set Ready" (DSR),  "Clear  To  Send"
  489.               (CTS),  "Ring Indicator" (RI), and "Data Carrier Detect" (DCD). SioModem can
  490.               read any of the modem status bits.  SioDSR, SioCTS, SioRI,  and  SioDCD  can
  491.               only  read  their respective modem status bit. SioGetDiv reads the baud rate
  492.               divisor register so that the baud rate can be determined. SioRead reads  any
  493.               of the 7 UART registers.
  494.  
  495.               Refer  to  the  chapter entitled "RS232 Signals" for a discussion of each of
  496.               the control and status bits.
  497.  
  498.               SioDTR    - Set, clear, or read the Data Terminal Ready (DTR) bit.
  499.               SioRTS    | Sets, clears, or reads the Request to Send (RTS) line.
  500.               SioModem  | Reads the modem status register.
  501.               SioDSR    | Reads the Data Set Ready (DSR) modem status bit.
  502.               SioCTS    | Reads the Clear to Send (CTS) modem status bit
  503.               SioDCD    | Reads the Data Carrier Detect (DCD) modem status bit.
  504.               SioRI     | Reads the Ring Indicator (RI) modem status bit.
  505.               SioRead   | Reads the contents of the 7 UART registers.
  506.               SioGetDiv - Reads the baud rate divisor registers.
  507.  
  508.               2.4 Serial I/O
  509.  
  510.  
  511.               There  are  nine  library  functions  in the serial I/O category.  Together,
  512.               these functions give the programmer complete control over serial I/O. Higher
  513.               level functions such as protocols and  smart  modem  communications  can  be
  514.               completely  implemented  in  terms of these functions.  Refer to the example
  515.               code.
  516.  
  517.               SioGetc  and  SioPutc perform all the actual serial I/O.  SioUnGetc "ungets"
  518.               the last serial byte  read.   SioRxClear  clears  the  receive  queue  while
  519.               SioTxClear  clears  the  transmit queue.  SioTxFlush forces all bytes in the
  520.               transmit queue to be transmitted. SioRxQue returns the number  of  bytes  in
  521.               the receive queue while SioTxQue returns the number of bytes in the transmit
  522.               queue. SioLine can be used to test for UART errors.
  523.  
  524.               SioGetc    - Reads the next character from the serial line.
  525.               SioPutc    | Transmit a character over a serial line.
  526.               SioUnGetc  | "Un-gets" (puts back) a specified character.
  527.               SioRxClear | Clears the receive buffer.
  528.               SioRxQue   | Returns the number of characters in the receive queue.
  529.               SioTxClear | Clears the transmit buffer.
  530.               SioTxFlush | Flushes the transmit buffer.
  531.               SioTxQue   | Returns the number of characters in the transmit queue.
  532.               SioLine    - Reads the line status register.
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.              PCL4P Users Manual                                                Page 8
  545.               2.5 Error Detection
  546.  
  547.  
  548.               There are four functions in the error detection category. They are concerned
  549.               with  detecting  or reporting communications errors.  Use of these functions
  550.               can make your application significantly more robust.
  551.  
  552.               SioBrkKey can  be  used  as  an  "emergency"  exit  from  your  application.
  553.               SioBrkSig  can  read  or  modify  the  UART  break  bit.  This is useful for
  554.               signalling  the  remote  system  that  a  fatal  condition   has   occurred.
  555.               SioLoopBack  can  be  used  to  test  the  integrity of your UART.  SioError
  556.               displays a error message corresponding to an  error  code  returned  from  a
  557.               PCL4P function.
  558.  
  559.               SioBrkKey - Returns non-zero if the Control-BREAK key was pressed
  560.               SioBrkSig | Asserts, cancels, or detects  BREAK  signal.
  561.               SioError  - Displays  error  in  text.
  562.               SioLoopBack - Performs a UART loopback test.
  563.  
  564.  
  565.               2.6 General Support
  566.  
  567.  
  568.               There are three functions in the general support category.  Strictly speaking,
  569.               they  are not communications functions, but they take up a very small amount
  570.               of additional memory.  Registered users can remove these functions from  the
  571.               library if needed.
  572.  
  573.               SioInfo     - Returns the library version, RX & TX interrupts, etc.
  574.               SioTimer    | Returns the number of system clock tics.
  575.               SioDelay    - Delays one or more timer tics (18.2 tics per second).
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.              PCL4P Users Manual                                                Page 9
  613.               3.0 Library Overview
  614.  
  615.               3.1 Using the Library
  616.  
  617.  
  618.               The  PCL4P  library  has  been  tested on a Tandy 1000 (4.77 MHZ 8088 IBM PC
  619.               clone), a Tandy 3000 (80286 IBM AT clone), a Tandy 1400LT (IBM XT clone),  a
  620.               Gateway  2000 386(25 MHZ 80386-DX), and a Gateway 2000 486(66 MHX 80486-DX).
  621.               PCL4P has been tested under MSDOS 2.11, 3.2, 3.3, 4.01, 5.0, 6.0,  and  6.2.
  622.               The  PCL4P  library has also been compiled and tested using Turbo Pascal 6.0
  623.               and 7.0 as well as Borland Pascal 7.0.
  624.  
  625.               Please examine the PCL4P.PAS file. Note that COM1 is defined as  port  zero,
  626.               not  port  one.   The  user  must  assume  the responsibilty for passing the
  627.               correct information when calling PCL4P functions.
  628.  
  629.  
  630.               3.2 Protected Mode
  631.  
  632.  
  633.               Protected mode programming takes advantage of the segmented architecture  of
  634.               286  and  up  Intel processors.  In contrast to normal real mode programming
  635.               which limits programs to an address space of 1 MB (1024 KB), protected  mode
  636.               allows  up  to  16 MB (in 16-bit protected mode). Protected mode also offers
  637.               some measure of protection of one program from another.
  638.  
  639.               A program that can excecute in  protected  mode  under  DOS  requires  three
  640.               modules:
  641.  
  642.               (1) A DPMI (DOS Protected Mode Interface) driver loaded in memory.
  643.  
  644.               (2) A protected mode runtime library linked to your program.
  645.  
  646.               (3) A runtime module which provides protected mode equivalents of:
  647.  
  648.                   a) A subset of DOS interrupt 21H calls.
  649.                   b) A subset of BIOS calls.
  650.                   c) Additional functions such as protected mode memory management.
  651.  
  652.               The  Personal  Communications Library (PCL4P16.TPP) supports protected mode.
  653.               Be sure to create PCL4P16.TPP and USE_DPMI.TPP by  running  the  batch  file
  654.               BP_PROT.BAT.   An  application program can then be compiled with the Borland
  655.               Pascal compiler, which supports 16-bit protected mode.
  656.  
  657.               Examine the example program SIMPLE16.PAS, which is a protected mode  version
  658.               of  the  normal  DOS  based  SIMPLE.PAS. Compare it to SIMPLE.PAS to see the
  659.               differences necessary to run in protected mode.
  660.  
  661.               In particular, note the manner in which memory is  allocated  for  use.  The
  662.               transmit  and  receive  buffers must be allocated in conventional DOS memory
  663.               (the first 1MB) since serial interrupts can occur during both protected mode
  664.               and real mode.
  665.  
  666.               Compile the protected mode program SIMPLE16.PAS using
  667.  
  668.                     BPC /CP SIMPLE16.PAS
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.              PCL4P Users Manual                                                Page 10
  681.               3.3 Applications Notes
  682.  
  683.               3.3.1 Terminal Programs
  684.  
  685.  
  686.               The  "terminal  program" is the most common class of communications program.
  687.               It is used to call up a BBS or on-line service such as  CompuServe,  America
  688.               On-Line,  etc.   Refer  to  the  programs  SIMPLE and LOGIN in section 7 for
  689.               examples of simple terminal programs.
  690.  
  691.               A  more  sophisticated terminal program featuring ASCII, XMODEM, YMODEM, and
  692.               ZMODEM protocol file transfers can be found in our  sister  product  --  The
  693.               Personal  Protocol Library (PPL4P). Source code is included in the shareware
  694.               distribution for everything except ZMODEM and the script interpreter.
  695.  
  696.  
  697.               3.3.2 Door Programs
  698.  
  699.  
  700.               In order to write a door program which "takes over" a  serial  port  without
  701.               resetting  the  port or changing the baud rate, call SioReset() with NORESET
  702.               as the second argument rather than the baud rate. Call  SioGetDiv()  to  get
  703.               the  baud  rate divisor if the baud rate must be determined. Be sure to call
  704.               SioDone() before returning to the invoking program.  Refer to  the  DOOR.PAS
  705.               example program.
  706.  
  707.  
  708.               3.3.3 BBS Programs
  709.  
  710.  
  711.               If you are designing a BBS program (also known as HOST  programs),  consider
  712.               using  16550  UARTS.   You  should  also choose a multiport card such as the
  713.               DigiBoard or BOCA board if you wish to run more than 4 ports simultaneously.
  714.  
  715.               If  you  are using an error correcting modem, then you should be sure to set
  716.               flow control and fix your baud rate at the highest possible transfer  rates.
  717.               For  14,400  modems, this means 19200 or 38400. For 28,800 modem, this means
  718.               38400 or 57600. Consult your modem manual for the correct  baud  rate.   You
  719.               may also need a 16550 UART in order to run at the higher speed.
  720.  
  721.               If you are using an older multi-speed modem (say  1200,  2400,  4800,  9600)
  722.               that doesn't use flow control, you should change your baud rate to match the
  723.               CONNECT message baud rate.
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.              PCL4P Users Manual                                                Page 11
  749.               3.4 Compiling and Linking
  750.  
  751.  
  752.               The  Personal  Communications  Library for Pascal supports both Turbo Pascal
  753.               and Borland Pascal. Substitute BCP for  TPC  in  the  following  if  Borland
  754.               Pascal is being used.
  755.  
  756.               Registered  users  may  wish  to assemble PCL4P.ASM. To create the real mode
  757.               library object with transmitter interrupts enabled:
  758.  
  759.                     TASM PCL4P.ASM,PCL4P.OBJ /DPASCAL_MODEL;
  760.                     TPC PCL4P.PAS
  761.  
  762.               To create the real mode library object with transmitter interrupts disabled:
  763.  
  764.                     TASM PCL4P.ASM,PCL4P.OBJ /DPASCAL_MODEL /DNO_TBE;
  765.                     TPC PCL4P.PAS
  766.  
  767.               For protected mode [Borland Pascal only]:
  768.  
  769.                     TASM USE_DPMI.ASM /MX;
  770.                     TASM PCL4P.ASM,PCL4P16.OBJ /DPASCAL_MODEL /DDPMI /MX;
  771.  
  772.               To create the real mode library PCL4P.TPU
  773.  
  774.                     TPC PCL4P.PAS
  775.  
  776.               To create the protected mode [Borland Pascal only] library PCL4P16.TPP
  777.  
  778.                     BPC /CP USE_DPMI.PAS
  779.                     BPC /CP PCL4P16.PAS
  780.  
  781.               To compile the sample programs:
  782.  
  783.                     TPC SIMPLE.PAS
  784.  
  785.               To compile the protected mode [Borland Pascal only] program SIMPLE16.PAS
  786.  
  787.                     BPC /CP SIMPLE16.PAS
  788.  
  789.  
  790.               3.5 Turbo Vision
  791.  
  792.  
  793.               The PCL4P library can also be used in Turbo  Vision  programs.  Examine  the
  794.               TVTERM.PAS for a simple example program analogous to the SIMPLE.PAS program.
  795.  
  796.               TVTERM  copies any keyboard input to the serial port and copies any incoming
  797.               serial port data to the screen. Type Alternate-X to exit.
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.              PCL4P Users Manual                                                Page 12
  817.               4.0 Talking to Your Modem
  818.  
  819.  
  820.               A modem is used to extend the  distance  over  which  you  may  communicate.
  821.               Without  a  modem, your RS232 cable is limited to a maximum of approximately
  822.               50 feet.  But with a modem, you can communicate literally around the world.
  823.  
  824.               Also refer to the Section 4.3, "MODEM_IO  functions"  for  details  on  MODEM_IO
  825.               functions. These functions facilitate communications with modems.
  826.  
  827.               4.1 Modem Standards
  828.  
  829.  
  830.               Two modems can communicate over a telephone line only if they are both using
  831.               the same signaling frequencies and modulation, which are determined  by  the
  832.               the  modem  standards used.  Modem standards can be divided into three sets:
  833.               (1) speed, (2) data compression used, and (3) error control.
  834.  
  835.               The Bell standards  (103  &  212A)  are  those  of  AT&T.   The  CCITT  (The
  836.               International  Consultative Committee for Telephone and Telegraph) standards
  837.               are designated as "V. ".
  838.  
  839.  
  840.               Speed
  841.  
  842.               Bell 103  -   300 baud
  843.               Bell 212A |  1200 baud
  844.               V.21      |   300 baud
  845.               V.22bis   |  1200 & 2400 baud
  846.               V.32      |  4800 & 9600 baud
  847.               V.32bis   |  4800, 7200, 9600, 12000, and 14400 baud
  848.               V.34      -  through 28800 baud
  849.  
  850.               Data Compression
  851.  
  852.               MNP 5     -  Microcom Networking Protocol (proprietary).
  853.               V.42bis   -  International data compression standard.
  854.  
  855.  
  856.               Error Control
  857.  
  858.               MNP 2,3,4 -  Three level error correction (public domain).
  859.               V.42      -  International error correction standard.
  860.  
  861.               Most  of  the  newer  high  speed modems use several of the above standards.
  862.               However, not all combinations of modem makes communicate  easily  with  each
  863.               other, especially at high speed (9600 and up).
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.              PCL4P Users Manual                                                Page 13
  885.               4.2 Flow Control
  886.  
  887.  
  888.               With modems using data compression, the modem to modem connection  will  run
  889.               at  various  speeds  depending  on the quality of the line.  The computer to
  890.               modem connection will be at a fixed baud rate. Therefore, a  protocol  (flow
  891.               control)  is  necessary to synchronize the data flow between a modem and the
  892.               computer to  which  it  is  connected.   Refer  to  your  modem  manual  for
  893.               information on flow control protocols supported.
  894.  
  895.               Two  flow  control  protocols  are  used  by  most modems which require flow
  896.               control. Software flow control is called  "XON/XOFF"  (other  software  flow
  897.               control  character  pairs  are defined but operate the same as XON/XOFF) and
  898.               hardware flow control is called "RTS/CTS".  Most modems which  require  flow
  899.               control enable hardware flow control by default.
  900.  
  901.               In XON/XOFF (software) flow control, the computer suspends transmitting data
  902.               if  it  receives  a  XOFF  character  (13 hex) from the modem, and continues
  903.               transmitting when it receives a XON character  (11  hex).   Similiarly,  the
  904.               computer  can  signal  the modem not to send any more data by transmitting a
  905.               XOFF to it, and can tell the modem to continue  transmission  be  sending  a
  906.               XON.
  907.  
  908.               In  RTS/CTS (hardware) flow control, the RTS line is used by the computer to
  909.               signal the modem , while the CTS line is used by the  modem  to  signal  the
  910.               computer.   The  RTS  line  is  set OFF by the computer to tell the modem to
  911.               suspend  transmission,  and  set  to  ON  to  tell  the  modem  to  continue
  912.               transmission.   The CTS line is set to OFF by the modem to tell the computer
  913.               to stop transmitting, and set  to  ON  to  tell  the  computer  to  continue
  914.               transmitting.
  915.  
  916.               Given  the  choice,  always  choose hardware flow control over software flow
  917.               control so that all data transmission  is  transparent.   If  hardware  flow
  918.               control  is  not  the default (which it almost always is), you should modify
  919.               your modem initialization string to turn hardware flow control on.
  920.  
  921.  
  922.               4.3 MODEM_IO Functions
  923.  
  924.  
  925.               The  file  MODEM_IO.PAS  contains  several functions that ease communicating
  926.               with your modem.  Look in the LOGIN.PAS code for examples of their use.
  927.  
  928.                    ModemSendTo   : Sends string (including control chars) to the modem.
  929.                    ModemWaitFor  : Waits for a particular string from the modem, passing
  930.                                    all else through.
  931.                    ModemQuiet    : Waits for continuous quiet of specified duration.
  932.                    ModemHangup   : Hangs up the modem.
  933.                    ModemCmdState : Goes into the modem's command state.
  934.                    ModemEcho     : Echos all serial incoming bytes to the display.
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.              PCL4P Users Manual                                                Page 14
  953.               4.4 Modem Initialization
  954.  
  955.  
  956.               If your application uses a modem (as opposed to using a null  modem  cable),
  957.               then  you should always send an initialization string to your modem if it is
  958.               a programmable modem such as those made by  Hayes.   Communication  programs
  959.               such as PROCOMM and TELIX always send such a string automatically as soon as
  960.               they start up.
  961.  
  962.               The particular initialization string depends on the make of your modem.  For
  963.               Hayes  and  Hayes  AT  command  set  compatible modems, the following string
  964.               (followed by a carriage return) should work:
  965.  
  966.                    AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  967.  
  968.               Refer to your Modem User's Guide for a full discussion of these commands.  A
  969.               brief description is as follows:
  970.  
  971.               AT     Modem attention command.
  972.               E1     Modem will echo what you send to it.
  973.               S7=60  Wait 60 seconds for carrier and/or dial tone.
  974.               S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  975.               V1     Display result code as words (not numbers).
  976.               X1     Use the extended result message (CONNECT XXXX) set.
  977.               Q0     Modem returns result codes.
  978.               S0=0   Do not answer RING.
  979.  
  980.               If  your application will answer incoming calls, then set the S0 register to
  981.               the ring on which to automatically answer.
  982.  
  983.               If you send the above codes by using SioPutc (as opposed to typing them from
  984.               the keyboard), then follow these guidelines:
  985.  
  986.               (1) Send an initial carriage return before the initialization string.
  987.  
  988.               (2) Pause at least two tics (18 tics to the  second)  after  each  character
  989.               sent  as  your  modem needs the time to perform its own internal processing.
  990.               Pause a little longer if your modem is  not  accepting  your  initialization
  991.               string.
  992.  
  993.               (3)  Pause  one  and a half seconds after sending any initialization command
  994.               such as ATZ or AT&F since your modem must do quite a bit of processing.
  995.  
  996.               If you experience any problems in initializing your Hayes modem, you  should
  997.               first reset it to factory settings by sending:
  998.  
  999.                    AT&F
  1000.  
  1001.               Refer  to  the  TERM  program  (functions  SendTo  and  WaitFor  in the file
  1002.               MODEM_IO.PAS) for an example of sending an initialization string to a  Hayes
  1003.               compatible modem.
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.              PCL4P Users Manual                                                Page 15
  1021.               5.0 Problems
  1022.  
  1023.  
  1024.               If  you  cannot  get your application to run properly, first compile and run
  1025.               the terminal emulator program TERM provided on your distribution  disk.   If
  1026.               you are using a null modem cable or a non-programmable modem, be sure not to
  1027.               define  AT_COMMAND_SET  in DEFINES.PAS.  If you are using a Hayes compatible
  1028.               modem, then do define AT_COMMAND_SET {$DEFINE AT_COMMAND_SET}.  If  you  are
  1029.               using  a  programmable  modem  which  is not Hayes compatible, then you must
  1030.               modify the initialization string for your particular modem.
  1031.  
  1032.               If your application does not run but TERM runs correctly, then you have most
  1033.               likely  made  a  programming  mistake  in  your  application.   MarshallSoft
  1034.               Computing  cannot  debug  your  application,  especially over the telephone!
  1035.               However, consider each of the following when searching for an error in  your
  1036.               application.
  1037.  
  1038.               1.  Did you include the "uses PCL4P" statement ?
  1039.  
  1040.               2.  Is your receive buffer large enough ? If you are using 1K data blocks in
  1041.               YMODEM,  then  your  receive buffer should be at least 1K ( 2K if baud rates
  1042.               above 38400 are to be used ).
  1043.  
  1044.               4.  Have you selected too high a baud rate ( if you are using a slow PC )  ?
  1045.               If  only  one COM port is being run, you should be able to run at 38400 baud
  1046.               on 8088 machines and 115200 on most 286 and all 386 and 486 machines.
  1047.  
  1048.               5.  Are you attempting to run another application in the background  ?   Try
  1049.               running  without  any  other programs running in the background ( unload all
  1050.               TSR programs ).
  1051.  
  1052.               6.  If you are running two COM ports simultaneously, are you using  separate
  1053.               receive buffers ? ( you should ).
  1054.  
  1055.               7.   Did SioReset return a zero value ?  If not, then you must call SioReset
  1056.               again. See TERM.PAS for an example.
  1057.  
  1058.               8.  Did you send the proper initialization string to your modem  ?  Did  you
  1059.               set DTR and RTS ? ( you should ).
  1060.  
  1061.               9.   Do  you  have more than one COM1 port, etc.  For example, if you have a
  1062.               COM1 port on your motherboard, you cannot add another  COM1  port  or  modem
  1063.               board that uses COM1 without first disabling the COM1 on the motherboard.
  1064.  
  1065.               10. Are you passing the proper segment of the receive (or transmit) buffer?.
  1066.               See SIMPLE.PAS or TERM.PAS for an example.
  1067.  
  1068.               Registered  users  can  call  (205)  881  - 4630 from 1:30 PM to 9:30 PM CST
  1069.               Monday through Friday for help.
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.              PCL4P Users Manual                                                Page 16
  1089.               6.0 Serial Communications
  1090.  
  1091.  
  1092.               6.1 Communications Basics
  1093.  
  1094.  
  1095.               The heart of serial  communications  is  the  UART  (Universal  Asynchronous
  1096.               Receiver  Transmitter).   The  IBM PC/XT/AT and compatibles use the INS8250,
  1097.               INS16450, or the INS16550 UART.  The purpose of the UART is:
  1098.  
  1099.               (1) To convert bytes from the CPU (Central Processing Unit), into  a  serial
  1100.               format  by  adding  the  necessary start, stop, and parity bits to each byte
  1101.               before transmission, and to then transmit each bit at the correct baud rate.
  1102.  
  1103.               (2) To convert the incoming stream (at a specified baud rate) of serial bits
  1104.               into bytes by removing the start, stop, and parity bits  before  being  made
  1105.               available to the CPU.
  1106.  
  1107.               The  UART  is part of the serial interface circuitry which allows the CPU to
  1108.               send and receive signals over the RS232 lines. This  can  be  diagrammed  as
  1109.               follows:
  1110.  
  1111.  
  1112.  
  1113.                                     Serial Interface
  1114.                                  +-------------------+
  1115.                                  |                   |
  1116.               +-----+  Data Bus  |     +------+      |    RS232 Signals
  1117.               | CPU +------------+     | UART |      +----------------*
  1118.               +-----+            |     +------+      |
  1119.                                  |                   |
  1120.                                  +-------------------+
  1121.  
  1122.  
  1123.  
  1124.               The  INS8250/16450/16550  UART  is capable of operating in one of two modes,
  1125.               "polled" and "interrupt driven".  The serial communications functions in the
  1126.               BIOS uses the polled method.  In this approach, the CPU is  typically  in  a
  1127.               loop  asking  the  UART  over  and over again if it has a byte ready. If its
  1128.               does, the polling code returns the byte.  But, if the  next  byte  comes  in
  1129.               before the polling code is executing again, then that byte is lost.
  1130.  
  1131.               In  the  interrupt driven approach (used by PCL4P for incoming data), when a
  1132.               byte is received by the  UART,  an  "Interrupt  Service  Routine"  (ISR)  is
  1133.               executed immediately, suspending temporarily whatever else is executing. The
  1134.               ISR  then  moves  the  byte to a buffer so that your application program can
  1135.               later read it.  Refer to Sections 6.6 and 6.7 entitled "RS232  Signals"  and
  1136.               "National  INS8250,  INS16450  and INS16550 UARTs", respectively for further
  1137.               information on these topics.
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.              PCL4P Users Manual                                                Page 17
  1157.               6.2 Standard Port Addresses
  1158.  
  1159.  
  1160.               There  are  a  few  things to know about how serial communications ports are
  1161.               used by IBM PC/XT/AT and compatible computers.  The  standard  IBM  PC/XT/AT
  1162.               configuration values are as follows:
  1163.  
  1164.               Port     Reg Base   IRQ Line   Vector
  1165.               COM1        3F8H        4        12
  1166.               COM2        2F8H        3        11
  1167.               COM3        3E8H        4        12
  1168.               COM4        2E8H        3        11
  1169.  
  1170.               (Refer  to your DigiBoard manual for DigiBoard addresses, or your BOCA board
  1171.               manual for BOCA port addresses).
  1172.  
  1173.               PCL4P assumes the above values.  If necessary, the UART base address can  be
  1174.               changed by SioUART, and IRQ lines can be re-assigned by SioIRQ. Refer to the
  1175.               PCL4P Reference Manual for specific details.
  1176.  
  1177.               When  installing  new  communications  cards,  the  following guidelines are
  1178.               recommended:
  1179.  
  1180.               (1) Be sure to read the documentation for the hardware you  are  installing.
  1181.               Pay special attention to UART base addresses and IRQ lines.
  1182.  
  1183.               (2)  If  you  have  a  choice in base addresses and IRQ lines, always choose
  1184.               standard values as defined above.
  1185.  
  1186.               (3) The first port should be COM1, the second COM2, etc.  Do NOT  skip  over
  1187.               any port. This problem has caught several users.
  1188.  
  1189.               (4)  Use SioUART to zero all unused ports (for example, call SioUART(COM4,0)
  1190.               if there is no COM4 port installed).
  1191.  
  1192.               (5) Be carefull not to configure two ports for the  same  address.  This  is
  1193.               easier to do than you may believe.
  1194.  
  1195.               (6)  Choose  an  external  modem over an internal one.  It is much easier to
  1196.               debug problems with an external modem than an internal one.
  1197.  
  1198.               (7) Select hardware flow control (RTS/CTS) if flow control is  required  and
  1199.               hardware flow control is not the default.
  1200.  
  1201.               (8) Always test your port as soon as it is installed.
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.              PCL4P Users Manual                                                Page 18
  1225.               6.3 Running 3 or 4 Ports Concurrently
  1226.  
  1227.  
  1228.               PCL4P supports up to 4 serial ports running concurrently (more if you have a
  1229.               DigiBoard or BOCA board).  One free interrupt for each port is required. The
  1230.               following assumes that you don't have a DigiBoard.
  1231.  
  1232.               Interrupts  IRQ4  and  IRQ3  are  dedicated to the communications ports in a
  1233.               standard IBM PC/XT/AT configuration.  IRQ4 is shared between COM1  and  COM3
  1234.               while IRQ3 is shared between COM2 and COM4.  This means that you can run two
  1235.               ports simultaneously provided that they don't share an interrupt.
  1236.  
  1237.               Suppose that you wish to run 3 ports simultaneously. To begin, you must have
  1238.               3  serial  UARTs  installed  on your computer.  Assume, for purposes of this
  1239.               discussion, that COM1 is installed on your motherboard, and  that  you  have
  1240.               purchased a new 2 port serial communications board.
  1241.  
  1242.               You  should  be able to configure the first serial board port as COM2, which
  1243.               uses IRQ3.  Refer to the manual that came with your serial board.
  1244.  
  1245.               In order to run the third serial port concurrently with  the  first  two,  a
  1246.               unused  interrupt  must be found.  If your serial card can only use IRQ3 and
  1247.               IRQ4, then there is no way to run a third line since IRQ4 and IRQ3 are  used
  1248.               for COM1 and COM2.
  1249.  
  1250.               However,  many serial cards can use other IRQs, typically IRQ2 through IRQ5.
  1251.               Since IRQ5 is normally used  for  a  second  printer  port,  it  is  a  good
  1252.               candidate  for  COM3.  To use IRQ5 for the third serial port, first set your
  1253.               serial card to use IRQ5 for COM3 (refer to your serial card manual) and then
  1254.               add the following line to your applications code before calling SioReset:
  1255.  
  1256.                      RetCode := SioIRQ(COM3,IRQ5);
  1257.  
  1258.               Don't forget to disable any device that might use IRQ5,  such  as  a  second
  1259.               printer  port  or  a  music  card.   Unfortunately,  there is no easy way to
  1260.               determine that you have no conflicts until you actually attempt to  use  the
  1261.               IRQ.  If  there  are  conflicts, your system will probably hang and you will
  1262.               have to reboot.
  1263.  
  1264.               To run a fourth serial port, another  free  IRQ  must  be  found.   On  some
  1265.               systems, IRQ7 can be used. To use IRQ7 for the fourth serial port, first set
  1266.               your serial card to use IRQ7 for COM4 and then add:
  1267.  
  1268.                      RetCode := SioIRQ(COM4,IRQ7);
  1269.  
  1270.               To  summarize,  your  serial  card must be able to generate the correct IRQ,
  1271.               which is not already being used. Refer to the entry for the SioIRQ  function
  1272.               in the PCL4P Reference Manual.
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.              PCL4P Users Manual                                                Page 19
  1293.               6.4 Using the DigiBoard
  1294.  
  1295.  
  1296.               PCL4P  supports the the dumb DigiBoard (PC/4 & PC/8) and the dumb BOCA board
  1297.               (BB1004, BB1008, and BB2016).
  1298.  
  1299.               6.4.1 The DigiBoard
  1300.  
  1301.               Your PCs ports must be partitioned into "standard" PC  ports  and  DigiBoard
  1302.               ports.  Remember that standard PC ports cannot share IRQs like the DigiBoard
  1303.               can.  If  you  are  using IRQ4 and IRQ3 for standard PC ports COM1 and COM2,
  1304.               then you cannot use either for DigiBoard ports (try IRQ5 or IRQ7).
  1305.  
  1306.               Suppose that COM1 through COM2 are standard PC ports (using IRQ4  and  IRQ3)
  1307.               and  you  have  installed  a  PC/8  DigiBoard  that you wish to use for COM3
  1308.               through COM10 using interrupt line IRQ5.  You choose to use the  recommended
  1309.               DigiBoard UART addresses starting at $100:
  1310.  
  1311.               Code := SioPorts(10,COM3,$140,DIGIBOARD);
  1312.               Address := $100;                (* 1st DigiBoard UART address *)
  1313.               for Port:=COM3 to COM10 do      (* look at each port *)
  1314.                 begin
  1315.                   Code := SioUART(Port,Address);     (* set the UART address *)
  1316.                   Address := Address + 8;            (* next DigiBoard UART *)
  1317.                   Code := SioIRQ(Port,IRQ5);         (* set the IRQ & ISR *)
  1318.                 end
  1319.  
  1320.               The  DigiBoard uses $140 for the status address for odd interrupts and 0x141
  1321.               for even interrupts.
  1322.  
  1323.               DigiBoard may be contacted at 6400 Flying  Cloud  Drive,  Eden  Prairie,  MN
  1324.               55344.  Telephone 612-943-9020. FAX 612-943-5398.
  1325.  
  1326.               6.4.2 The BOCA Board
  1327.  
  1328.               PCL4P  supports  the  dumb  BOCA  board.  As  with  the  DigiBoard, you must
  1329.               configure PCL4P before using the BOCA board.
  1330.  
  1331.               For example, to configure the BOCA BB2016 to use COM1  to  COM16  with  base
  1332.               addresses starting at $100 and using IRQ15:
  1333.  
  1334.               Code := SioPorts(16,COM1,$107,BOCABOARD);
  1335.               Address := $100;                (* 1st DigiBoard UART address *)
  1336.               for Port:=COM1 to COM16 do      (* look at each port *)
  1337.                 begin
  1338.                   Code := SioUART(Port,Address);     (* set the UART address *)
  1339.                   Address := Address + 8;            (* next DigiBoard UART *)
  1340.                   Code := SioIRQ(Port,IRQ15);        (* set the IRQ & ISR *)
  1341.                 end
  1342.  
  1343.               BOCA  may  be  contacted at BOCA Research, Inc., 6413 Congress Avenue, Suite
  1344.               130, Boca Raton, FL 33487. Phone 407-241-8088, FAX 407-997-0918.
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.              PCL4P Users Manual                                                Page 20
  1361.               6.5 Transmitter Interrupts
  1362.  
  1363.  
  1364.               Beginning  in  version 4.0 of PCL4P, transmitter interrupts are supported by
  1365.               the  library.   Separate  libraries  are  provided,  one  with   transmitter
  1366.               interrupts  enabled  (the  default  beginning  with  version  5.1)  and  one
  1367.               without.  When transmitter interrupts are NOT enabled, the  following  logic
  1368.               occurs everytime you call SioPutc:
  1369.  
  1370.                1.  Wait  for  transmit buffer to become empty. The transmit buffer may not
  1371.               be empty if the previous transmit is not completed (the UART breaks down the
  1372.               byte & sends 1 bit at a time). 2. When the transmit  buffer  is  empty,  the
  1373.               byte from the SioPutc call is loaded into the transmit buffer and control is
  1374.               returned to the caller.
  1375.  
  1376.               Note that you can not write to the UART any faster the the UART baud rate.
  1377.  
  1378.               When transmitter interrupts are enabled, the byte from SioPutc is put into a
  1379.               previously  prepared  (by SioTxQue) transmitter queue. The interrupt service
  1380.               routine fetches bytes from this queue as soon as the previous byte has  been
  1381.               sent.
  1382.  
  1383.               While  you  can  now call SioPutc faster than the baud rate, bytes are still
  1384.               transmitted at the given baud rate.
  1385.  
  1386.               The   above   sounds   like  transmitter  interrupts  are  the  way  to  go.
  1387.               Unfortunately, this is often NOT the case.  Most applications  will  perform
  1388.               better if transmitter interrupts are NOT enabled.
  1389.  
  1390.               The  reason  is that transmitter interrupts double the amount of code in the
  1391.               time critical interrupt service routines.  While the library is processing a
  1392.               transmitter interrupt (which can take a while), incoming bytes  can  not  be
  1393.               processed.  What this means is that a given machine can run at a higher baud
  1394.               rate without transmitter interrupts. This problem is compounded when running
  1395.               multiple ports simultaniously.
  1396.  
  1397.               However, there are some application areas where transmitter  interrupts  are
  1398.               preferable.   If  your  application  will  be transmitting blocks of data at
  1399.               fairly slow baud rates you might profit from enabling transmitter interrupts
  1400.               provided that there is something else for the processor to do (which is  NOT
  1401.               the case in most protocols under DOS).
  1402.  
  1403.               The  default  library is with transmitter interrupts enabled.  To create the
  1404.               PCL4P  library  without  TX  interrupts  enabled,  copy  "PCL4PN.OBJ"   over
  1405.               "PCL4P.OBJ"  in  TP_REAL.BAT  (or  BP_REAL.BAT) and then execute TP_REAL (or
  1406.               BP_REAL).
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.              PCL4P Users Manual                                                Page 21
  1429.               6.6 RS-232 Signals
  1430.  
  1431.  
  1432.               RS-232 is the name of the serial data interface  standard  used  to  connect
  1433.               computers  to modems.  Most IBM compatible computers are built with at least
  1434.               one serial port and use either DB9 (9 pin) or DB25 (25 pin) connectors.
  1435.  
  1436.               A summary of these pins and  their  function  follows.   For  more  detailed
  1437.               information, refer to one of the many books dealing with RS-232 interfacing.
  1438.  
  1439.               Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  1440.  
  1441.               The  SG  line  is  used  as  the  common  signal  ground, and must always be
  1442.               connected.
  1443.  
  1444.               Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  1445.  
  1446.               The TX line is used to carry data from the computer to the modem.
  1447.  
  1448.               Receive Data Pin 3 (DB25), Pin 2 (DB9)
  1449.  
  1450.               The RX line is used to carry data from the modem to the computer.
  1451.  
  1452.               Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  1453.  
  1454.               The DTR line is used by the computer to signal the modem that it  is  ready.
  1455.               DTR should be set high when talking to a modem.
  1456.  
  1457.               Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  1458.  
  1459.               The DSR line is used by the modem to signal the computer that it is ready.
  1460.  
  1461.               Request to Send Pin 4 (DB25), Pin 7 (DB9)
  1462.  
  1463.               The  RTS  line  is used to "turn the line around" in half duplex modems, and
  1464.               for hardware flow control in most modems that require flow control.
  1465.  
  1466.               Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  1467.  
  1468.               The CTS line is used to "turn the line around" in half  duplex  modems,  and
  1469.               for hardware flow control in most modems that require flow control.
  1470.  
  1471.               Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  1472.  
  1473.               The DCD line is used by the modem to signal the computer that a data carrier
  1474.               signal is present.
  1475.  
  1476.               Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  1477.  
  1478.               The RI line is asserted when a 'ring' occurs.
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.              PCL4P Users Manual                                                Page 22
  1497.               6.7 National INS8250, INS16450, and INS16550 UARTs
  1498.  
  1499.  
  1500.               The  Personal  Communications  Library  is  based  on  the standard National
  1501.               INS8250, INS16450, and INS16550 UARTs. The 8250 was the original  UART  used
  1502.               in  the IBM PC, whereas the 16450 is a faster version found on most 286 & up
  1503.               machines. The 16550 contains a 16 byte FIFO to further reduce communications
  1504.               overhead. These UARTs consists of 8 register ports as follows:
  1505.  
  1506.               Offset    R/W   Register
  1507.                 0       R/W   Receiver (read) / Transmitter (write)
  1508.                 1       R/W   Interrupt Enable (read)
  1509.                 2       R     Interrupt Identification
  1510.                 2       W     FIFO control (INS16550 only)
  1511.                 3       R/W   Data Format (Line Control)
  1512.                 4       R/W   RS-232 (Modem) Control
  1513.                 5       R/W   Line Status
  1514.                 6       R/W   RS-232 (Modem) Status
  1515.                 7       R/W   Not used.
  1516.  
  1517.               The UART registers are based at 3F8 (COM1), 2F8 (COM2), 3E8 (COM3), and  2E8
  1518.               (COM4).  COM1  and COM3 share interrupt vector 12 and interrupt request line
  1519.               IRQ4 while COM2 and COM4 share interrupt vector  11  and  interrupt  request
  1520.               line  IRQ3.   This  means that COM1 and COM3 cannot both be used at the same
  1521.               time. Similarly, COM2 and COM4 cannot both be used at the same time.
  1522.  
  1523.  
  1524.               Port     Reg Base   IRQ Line   Vector
  1525.               COM1        3F8H        4        12
  1526.               COM2        2F8H        3        11
  1527.               COM3        3E8H        4        12
  1528.               COM4        2E8H        3        11
  1529.  
  1530.               Four sources of interrupts  are  possible  with  the  8250  and  16550:  (1)
  1531.               receiver error or BREAK, (2) receiver data ready, (3) ready to transmit, and
  1532.               (4)  RS232  input.   These  four  sources  of  interrupts  are summarized as
  1533.               follows:
  1534.  
  1535.               Source of Interrupt        Action Required to Clear
  1536.               Receiver error or BREAK.   Read Line Status register.
  1537.               Receiver data.             Read data from data register.
  1538.               Transmitter Buffer Empty.  Write to data register or read IID reg.
  1539.               RS232 input.               Read Modem Status register.
  1540.  
  1541.               However, PCL4P only enables the receiving data interrupt.  This  means  that
  1542.               interrupts can only be caused by incoming data.
  1543.  
  1544.               If you are not familiar with the INS8250, several good books are  available.
  1545.               Refer  to  Section  9.3,  Further  Reading  for recommendations.  Although a
  1546.               knowledge of the 8250 is not necessary to use PCL4P, a general knowledge  of
  1547.               the theory of asynchronous serial communications is recommended.
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.              PCL4P Users Manual                                                Page 23
  1565.               6.8 Register Summary
  1566.  
  1567.  
  1568.               REG 0 : Data Register
  1569.  
  1570.               Reading from the data register fetches the  next  input  byte,  once  it  is
  1571.               ready.   Writing  to the data register transmits the byte written to it over
  1572.               the serial line.
  1573.  
  1574.               REG 1 : Interrupt Enable 
  1575.  
  1576.               The Interrupt Enable register enables each of four types of interrupts  when
  1577.               the appropriate bit is set to a one.
  1578.  
  1579.               bit 3 : Enable  interrupt  on  RS232  input.
  1580.               bit 2 : Enable interrupt on receiver error or break.
  1581.               bit 1 : Enable  interrupt  on  transmitter  buffer empty(TBE).
  1582.               bit 0 : Enable interrupt on received data (RxRDY).
  1583.  
  1584.               REG 2 : Interrupt Identification (IID)
  1585.  
  1586.               Reading  the Interrupt Identification (read only) register once an interrupt
  1587.               has occurred identifies the interrupt as follows:
  1588.  
  1589.               Bit 2  Bit 1  Bit 0  Priority    Interrupt
  1590.                 0      0      1      none      none
  1591.                 1      1      0      0 (high)  Serialization or break.
  1592.                 1      0      0      1         Received data.
  1593.                 0      1      0      2         Transmitter Buffer Empty.
  1594.                 0      0      0      3 (low)   RS232 Input.
  1595.  
  1596.               In the INS16650, REG 2 (write only)  is  also  the  FIFO  control  register.
  1597.               Writing bits 6 & 7 will set the FIFO trigger level (number of bytes received
  1598.               before an interrupt is generated).
  1599.  
  1600.               Bit 7  Bit 6   Trigger             Bit 7  Bit 6   Trigger
  1601.                0      0      1 byte               1      0      8 bytes
  1602.                0      1      4 bytes              1      1      14 bytes
  1603.  
  1604.               REG 3 : Line Control
  1605.  
  1606.               RS232 line parameters are selected by writing to this register.
  1607.  
  1608.               bit 7 : DLAB = 0
  1609.               bit 6 : BREAK on(1), off(0).
  1610.               bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
  1611.               bit 2 : One stop bit(0), two stop bits(1).
  1612.               bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
  1613.  
  1614.               When  the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1 become the
  1615.               LS and MS bytes of the Baud Rate Divisor registers.
  1616.  
  1617.               Baud   Divisor      Baud  Divisor      Baud  Divisor
  1618.                300    0180        4800   0018       38400   0003
  1619.               1200    0060        9600   000C       57600   0002
  1620.               2400    0030       19200   0006      115200   0001
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.              PCL4P Users Manual                                                Page 24
  1633.               REG 4 : Modem Control
  1634.  
  1635.               RTS, DTR, loopback testing, and  General  Purpose  Outputs  #1  and  #2  are
  1636.               controlled by the Modem Control register as follows:
  1637.  
  1638.               bit 4 : Enable local loopback.
  1639.               bit 3 : Enable GP02. Necessary for 8250 interrupts.
  1640.               bit 2 : Enable GP01.
  1641.               bit 1 : Set / clear RTS.
  1642.               bit 0 : Set / clear DTR.
  1643.  
  1644.               REG 5 : Line Status
  1645.  
  1646.               Reading  the  Line Status register provides status information as follows (1
  1647.               for TRUE, 0 for FALSE) :
  1648.  
  1649.               bit 6 : Transmitter Empty.
  1650.               bit 5 : Transmitter Buffer Empty (TBE).
  1651.               bit 4 : BREAK detect.
  1652.               bit 3 : Framing error.
  1653.               bit 2 : Parity error.
  1654.               bit 1 : Overrun error.
  1655.               bit 0 : Data Ready.
  1656.  
  1657.               REG 6 : Modem Status
  1658.  
  1659.               Reading the Modem Status register provides the following status  information
  1660.               (1 for TRUE, 0 for FALSE) :
  1661.  
  1662.               bit 7 : DCD status.
  1663.               bit 6 : RI status.
  1664.               bit 5 : DSR status.
  1665.               bit 4 : CTS status.
  1666.               bit 3 : Delta DCD status.
  1667.               bit 2 : Delta RI status.
  1668.               bit 1 : Delta DSR status.
  1669.               bit 0 : Delta CTS status.
  1670.  
  1671.               The  delta  bits  (bits 0 through 3) are set whenever one of the status bits
  1672.               (bits 4 through 7) changes (from 0 to 1 or from 1 to 0) since the last  time
  1673.               that  the  Modem Status register was read. Reading the Modem Status register
  1674.               clear the delta bits.
  1675.  
  1676.               REG 7 : Scratch Register
  1677.  
  1678.               There is no function associated with register 7.  It does not exist in early
  1679.               versions of the 8250.
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.              PCL4P Users Manual                                                Page 25
  1701.               7.0 Example Programs
  1702.  
  1703.  
  1704.               Five example programs are include with PCL4P.   In  addition,  the  Personal
  1705.               Protocol Library for Pascal (PPL4P) includes the terminal program TERM which
  1706.               features  ASCII,  XMODEM,  YMODEM,  and ZMODEM protocol transfers.  Complete
  1707.               source code is included in the shareware product for all  of  the  protocols
  1708.               above  except  ZMODEM.   In  order  to  get  ZMODEM  source,  PPL4P  must be
  1709.               registered.
  1710.  
  1711.               7.1 MINIMAL
  1712.  
  1713.               MINIMAL is the simpliest possible communications program. It reads from  the
  1714.               serial port & displays on the screen and reads from the keyboard & sends out
  1715.               over the serial line. COM1 and 9600 baud are hard coded for simplicity.
  1716.  
  1717.               7.2 SIMPLE
  1718.  
  1719.               SIMPLE  is  a simple terminal program. It operates like MINIMAL, except that
  1720.               you specify both a port and a baud rate. For example.
  1721.  
  1722.                   SIMPLE 1 9600
  1723.  
  1724.               7.3 LOGIN
  1725.  
  1726.               LOGIN is programmed to dial our support BBS (205-880-9748)  and  log  on  as
  1727.               GUEST.  Start LOGIN like SIMPLE by providing a COM port and a baud rate. For
  1728.               example,
  1729.  
  1730.                  LOGIN 1 38400
  1731.  
  1732.               7.4 DOOR
  1733.  
  1734.               The  DOOR program is a simple communications program which can "take over" a
  1735.               serial port.  For example, say you  are  running  PROCOMM,  PCPLUS,  or  any
  1736.               communications  program  with  a  DOS  gateway.  Select the DOS gateway from
  1737.               PROCOMM (or whatever) and then type
  1738.  
  1739.                  DOOR 1
  1740.  
  1741.               at the DOS prompt to take over port COM1.
  1742.  
  1743.               7.5 SELFTEST
  1744.  
  1745.               The SELFTEST program is designed to test your serial ports provided that you
  1746.               have two ports which can be connected together  with  a  null  modem  cable.
  1747.               SELFTEST can also be used to test your multiport board.
  1748.  
  1749.               For example, to test PC port COM1 against COM2, type:
  1750.  
  1751.                  SELFTEST PC 1 2
  1752.  
  1753.               SELFTEST  may  need  to  be  configured  for  non-standard  PC ports or your
  1754.               multiport board. Refer to the SELFTEST source code for more information.
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.              PCL4P Users Manual                                                Page 26
  1769.               8.0 Legal Issues
  1770.  
  1771.               8.1 Registration
  1772.  
  1773.  
  1774.               If you wish to register the PCL4P library, please send $75 plus $5 S&H  ($10
  1775.               outside of North America) to:
  1776.  
  1777.                        MarshallSoft Computing, Inc.
  1778.                        Post Office Box  4543
  1779.                        Huntsville AL 35815
  1780.  
  1781.               Multiple copies are available: $55 for 3 to 9, $45 for 10 to 19, and $35 for
  1782.               20  or more.  A site license is also available for $675 (includes 20 sets of
  1783.               printed documentation). We pay shipping.
  1784.  
  1785.               We  accept  VISA,  MasterCard,  and  American   Express   (account   number,
  1786.               expiration  date, exact name on your card, and complete card billing address
  1787.               required), checks in US dollars drawn on a US bank,  purchase  orders  (POs)
  1788.               from recognized US schools and companies listed in Dun & Bradstreet, and COD
  1789.               (street  address and phone number required) within the USA (plus a $4.50 COD
  1790.               charge).
  1791.  
  1792.               You can also order PCL4P from The Public Software Library  (PSL)  with  your
  1793.               MC,  Visa,  AmEx,  or  Discover card by calling 800-242-4PSL (from overseas:
  1794.               713-524-6394) or by FAX at 713-524-6398 or  by  CompuServe  at  [71355,470].
  1795.               THESE  NUMBERS  ARE  FOR  ORDERING  ONLY.  PSL's product number for PCL4P is
  1796.               10909.  Please have your shipping address and credit  card  billing  address
  1797.               ready.
  1798.  
  1799.               If you wish to update from an older version of PCL4P, send $25 plus  $5  S&H
  1800.               ($10  outside  of  North  America).   Updates  must be ordered directly from
  1801.               MarshallSoft Computing.
  1802.  
  1803.               The registered package includes:
  1804.  
  1805.               o  Assembler source code for the library.
  1806.               o  Printed Users Manual.
  1807.               o  Printed Reference Manual.
  1808.               o  Technical support for one year.
  1809.  
  1810.               Print the file INVOICE.DOC if an invoice is needed. The registered user will
  1811.               receive the latest version of PCL4P shipped by two day priority mail (packet
  1812.               airmail overseas).  A 3.5" diskette is provided unless a 5.25"  diskette  is
  1813.               requested.
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.              PCL4P Users Manual                                                Page 27
  1837.               8.3 License
  1838.  
  1839.  
  1840.               MarshallSoft Computing, Inc. grants the registered user of PCL4P  the  right
  1841.               to  use  one copy of the PCL4P library (in object form) on a single computer
  1842.               in the development of any software product (other  than  libraries  such  as
  1843.               PCL4P).  The  user  may not use the library on more than one computer at the
  1844.               same time.  The source code for the library (PCL4P.ASM)  is  copyrighted  by
  1845.               MarshallSoft and may not be released in whole or in part.
  1846.  
  1847.               Products developed using PCL4P can include the object form  of  the  library
  1848.               and may be distributed without any royalty.
  1849.  
  1850.  
  1851.               8.4 Warranty
  1852.  
  1853.  
  1854.               MARSHALLSOFT COMPUTING, INC.  DISCLAIMS  ALL  WARRANTIES  RELATING  TO  THIS
  1855.               SOFTWARE,  WHETHER  EXPRESSED  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  1856.               IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE,
  1857.               AND  ALL  SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
  1858.               MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN  INVOLVED  IN  THE
  1859.               CREATION,  PRODUCTION,  OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
  1860.               INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1861.               INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.  HAS
  1862.               BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
  1863.               MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH  DAMAGES  EVER  EXCEED
  1864.               THE  PRICE  PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  1865.               OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
  1866.               AND PERFORMANCE OF THE SOFTWARE.
  1867.  
  1868.               Some states do not allow  the  exclusion  of  the  limit  of  liability  for
  1869.               consequential  or  incidental damages, so the above limitation may not apply
  1870.               to you.
  1871.  
  1872.               This agreement shall be governed by the laws of the  State  of  Alabama  and
  1873.               shall  inure  to  the  benefit  of  Marshallsoft  Computing,  Inc.   and any
  1874.               successors, administrators, heirs and  assigns.  Any  action  or  proceeding
  1875.               brought  by either party against the other arising out of or related to this
  1876.               agreement shall be brought only in a STATE or  FEDERAL  COURT  of  competent
  1877.               jurisdiction  located in Madison County, Alabama. The parties hereby consent
  1878.               to in personam jurisdiction of said courts.
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.              PCL4P Users Manual                                                Page 28
  1905.               9.0 Summary
  1906.  
  1907.               9.1 Revision History
  1908.  
  1909.  
  1910.               Version 1.0 - 14 January 1991 - original release.
  1911.  
  1912.               Version 1.1 - 11 March 1991
  1913.  
  1914.               o  Added SioUnGetc() function to library.
  1915.  
  1916.               Version 1.2 - 1 June 1991
  1917.  
  1918.               o  Name changed to Personal Communications Library.
  1919.               o  Minor bug fixes.
  1920.  
  1921.               Version 1.3 - 1 July 1991
  1922.  
  1923.               o  Added NORESET option to SioReset.
  1924.               o  Added SioDSR, SioCTS, SioDCD, and SioRI.
  1925.               o  Added SioLoopBack function to library.
  1926.               o  Added LOOPBACK.PAS example program.
  1927.  
  1928.               Version 2.0 - 1 Nov 1991
  1929.  
  1930.               o  All example code released in shareware package.
  1931.               o  Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.
  1932.  
  1933.               Version 3.0 - 15 Jan 1991
  1934.  
  1935.               o  Added XMODEM & YMODEM to example code.
  1936.               o  Added SioUART function.
  1937.               o  Added "UART undefined" error code.
  1938.               o  Added "Bad or missing UART" error code.
  1939.               o  Added "Port already enabled" error code.
  1940.               o  Added "Cannot enable both COM1 & COM3 ..." error code.
  1941.               o  Fixed several minor bugs ( using new automated testing ).
  1942.  
  1943.               Version 3.1 - 1 March 1992
  1944.  
  1945.               o  Added SioFIFO ( INS16550 only ).
  1946.               o  Added SioIRQ function.
  1947.               o  Increased maximum receive buffer size to 32K bytes.
  1948.  
  1949.               Version 3.2 - 1 May 1992
  1950.  
  1951.               o  Modified SioReset so that it no longer clears DTR & RTS.
  1952.               o  Modified SioModel & renamed to SioInfo.
  1953.               o  Fixed bug in SioDone when using 2 ports simultaneously.
  1954.               o  Added SioFlow to library.
  1955.               o  Added YMODEM-G protocol to TERM program.
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.              PCL4P Users Manual                                                Page 29
  1973.               9.1 Revision History (continued)
  1974.  
  1975.  
  1976.               Version 3.3 - 3 August 1992
  1977.  
  1978.               o  Fixed bug in SioUnGet when using 2 ports simultaneously.
  1979.               o  Add SioRead function.
  1980.  
  1981.               Version 3.4 - 4 Jan 1993
  1982.  
  1983.               o  Library modified to use up to four ports simultaneously.
  1984.               o  SioIRQ was modified to include  third argument.
  1985.               o  EXAMPORT utility distributed to registered users.
  1986.  
  1987.               Version 3.5 - 15 May 1993
  1988.  
  1989.               o  Supports DigiBoard PC/4 and PC/8.
  1990.               o  Two new error traps added ("No such IRQ" & "No such ISR").
  1991.               o  ASCII file transfer protocol added to TERM (with XON/XOFF).
  1992.  
  1993.               Version 4.0 - 18 Oct 1993
  1994.  
  1995.               o  The library supports transmitter interrupts.
  1996.               o  Corrects bug in Ver 3.5 requiring calling SioIRQ for COM3/4.
  1997.               o  The SioIRQ function has been simplified.
  1998.  
  1999.               Version 4.1 - 1 May 1994
  2000.  
  2001.               o  Transmitter FIFO enabled.
  2002.               o  Minor internal modifications.
  2003.               o  Supports dumb BOCA boards (BB1004, BB1008, & BB2016).
  2004.               o  Port definition extended to COM16.
  2005.  
  2006.               Version 4.2 - 1 Sept 1994
  2007.  
  2008.               o  Flow contro bug fixed.
  2009.               o  SioGetDiv function added.
  2010.               o  SioRxBuf and SioTxBuf function modified.
  2011.  
  2012.               Version 4.3 - 2 April 1995
  2013.  
  2014.               o  BREAK detection bug fixed.
  2015.               o  Port definitions extended to COM20.
  2016.               o  Support for IRQ8 through IRQ15.
  2017.               o  Line status bits preserved.
  2018.  
  2019.               Version 5.1 - 5 June 1996
  2020.  
  2021.               o  Supports 16-bit protected mode.
  2022.               o  SioRxFlush renamed to SioRxClear.
  2023.               o  SioTxFlush renamed to SioTxClear.
  2024.               o  Added (new) SioTxFlush [forces TX].
  2025.               o  Added more choices to SioInfo.
  2026.               o  Modified ISR logic for improved reliability.
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.              PCL4P Users Manual                                                Page 30
  2041.               9.2 Function Summary
  2042.  
  2043.  
  2044.               Refer to the PCL4P Reference Manual (PCL4P.REF) for detailed information  on
  2045.               the  communications  and  support  functions.  A  one  line  summary of each
  2046.               function follows:
  2047.  
  2048.  
  2049.               SioBaud     Sets the baud rate of the selected port.
  2050.               SioBrkKey   Returns non-zero if the Control-BREAK key was pressed.
  2051.               SioBrkSig   Asserts, cancels, or detects BREAK signal.
  2052.               SioCTS      Reads the Clear to Send (CTS) modem status bit.
  2053.               SioDCD      Reads the Data Carrier Detect (DCD) modem status bit.
  2054.               SioDelay    Delays one or more timer tics (18.2 tics per second).
  2055.               SioDone     Terminates further serial processing.
  2056.               SioDSR      Reads the Data Set Ready (DSR) modem status bit.
  2057.               SioDTR      Set, clear, or read the Data Terminal Ready (DTR) bit.
  2058.               SioError    Displays error in text.
  2059.               SioFIFO     Sets the interrupt level for the INS16550.
  2060.               SioFlow     Enables / disables hardware flow control.
  2061.               SioGetc     Reads the next character from the serial line.
  2062.               SioGetDiv   Reads the baud rate divisor.
  2063.               SioInfo     Returns library version number.
  2064.               SioIRQ      Assigns an IRQ line and interrupt service to a port.
  2065.               SioLine     Reads the line status register.
  2066.               SioLoopBack Performs a UART loopback test.
  2067.               SioModem    Reads the modem status register.
  2068.               SioParms    Sets parity, stop bits, and word length.
  2069.               SioPorts    Sets # ports, 1st DigiBoard / BOCA port & status reg.
  2070.               SioPutc     Transmit a character over a serial line.
  2071.               SioReset    Initialize a serial port for processing.
  2072.               SioRI       Reads the Ring Indicator (RI) modem status bit.
  2073.               SioRTS      Sets, clears, or reads the Request to Send (RTS) line.
  2074.               SioRead     Read any of the 7 UART registers.
  2075.               SioRxBuf    Sets up receive buffer.
  2076.               SioRxClear  Clears the receive buffer.
  2077.               SioRxQue    Returns the number of characters in the receive queue.
  2078.               SioTimer    Returns the number of system clock tics.
  2079.               SioTxBuf    Sets up transmit buffer.
  2080.               SioTxClear  Clears the transmit buffer.
  2081.               SioTxFlush  Flushes the transmit buffer.
  2082.               SioTxQue    Returns the number of characters in the transmit queue.
  2083.               SioUART     Sets the UART base address.
  2084.               SioUnGetc   "Un-gets" (puts back) a specified character.
  2085.  
  2086.  
  2087.               9.3 Further Reading
  2088.  
  2089.  
  2090.               The best way to learn about serial communications is to read a good book  on
  2091.               the  subject.  Several good texts are available.  Two that I like are (sorry
  2092.               but most communications books use C for their examples) :
  2093.  
  2094.               (1) C Programmers's Guide to Serial Communications by Joe Campbell (SAMS)
  2095.  
  2096.               (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  2097.  
  2098.               If you are interested in Protected Mode:
  2099.  
  2100.               (3) Borland Pascal 7.0 Language Manual
  2101.  
  2102.               (4) Extending DOS - A Programmer's Guild To Protected Mode DOS by Ray Duncan
  2103.               (Addison Wesley)
  2104.  
  2105.  
  2106.  
  2107.  
  2108.              PCL4P Users Manual                                                Page 31
  2109.               10.0 Other MarshallSoft Computing Products for Pascal
  2110.  
  2111.  
  2112.               10.1 The Personal Protocol Library for Pascal
  2113.  
  2114.  
  2115.               The Personal Protocol Library  for  Pascal  (PPL4P)  consists  of  a  Pascal
  2116.               language  library  which  implements  ASCII,  XMODEM, XMODEM-CRC, XMODEM-1K,
  2117.               XMODEM-G, YMODEM, YMODEM-G, and ZMODEM file transfer  protocols.   A  script
  2118.               compiler  and interpreter is also included which is capable of such tasks as
  2119.               automatically logging onto a BBS and downloading a file or retrieving  mail.
  2120.               Three example script programs are included.
  2121.  
  2122.               The protocol library (PPL4P) requires the  Personal  Communications  Library
  2123.               for Pascal (PCL4P).
  2124.  
  2125.               The  Personal  Protocol  Library for Pascal is available for $40 plus $5 S&H
  2126.               ($10 S&H overseas).
  2127.  
  2128.               10.2 The Personal Communications Library for DELPHI
  2129.  
  2130.               Coming this summer (1996) !
  2131.  
  2132.               11.0 Other Shareware Products
  2133.  
  2134.               We have DOS based communications and protocol libraries for  C/C++,  Pascal,
  2135.               Power Basic, and Visual Basic.
  2136.  
  2137.               We  have  Windows  based  products  for  C/C++ and Visual Basic, with DELPHI
  2138.               coming soon.
  2139.  
  2140.               All  of  our shareware products and example code is available on our support
  2141.               BBS  (205-880-9748,  14.4KB),   our   Internet   anonymous   FTP   site   at
  2142.               (ftp.marshallsoft.com/marshallsoft),  as  well  as many information services
  2143.               such as CompuServe, America Online, ExecPc, etc.
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.              PCL4P Users Manual                                                Page 32
  2177.  
  2178.